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1.0 INTRODUCTION 

The file FACT. SYS and its auxilliaries PACT.XOl, PACT.X02, 



• • • r 



FACT .XT? contain a transaction record of the activity 
on a DECsystem-lO timesharing system. The fact files are 
written by a variety of system programs v^en each user logs 
on or off the system, runs batch jobs, uses the I/O 
spoolers, and at ten-minute intervals throughout his use of 
the system. 



1.1 Standard Information 

Each entry includes an indication of why and when it was 
written, the job number to which it refers, the terminal 
running the job, and the project, programmer number of the 
user. In addition, many entries contain additional 
information relevant to the particular conditions under 
which they were written, such as the name of the program 
running, or statistics on useage of sharahle resources. 



1.2 Use of Auxilliary Files 

Ordinarily, all the information described in this document 
is output to SYS: FACT. SYS, by appending new entries to the 
end of the existing file, or by creating FACT. SYS if it does 
not exist. If, however, FACT. SYS should be inaecessable 
because of LOOKUP or ENTER failures, or because of being in 
a filo-being-modified state for ten seconds, each of the 
programs which writes FACT file information is set up to 
give up on FACT. SYS, and start trying to write FACT.XOl. If 
this fails, FACT.X02 is tried, and so on, counting in octal, 
to FACT.X77. If all 64 files are inaecessable, the message 

ACCOUirriNG SYSTEM FAILURE.... 
CALL THE OPERATOR. 

is printed, and the entry is not written. Note that, 
because the condition which makes a file inaecessable may be 
cleared, FACT. SYS (for instance) may contain entries both 
before and after those in FACT.XOl. Programs which depend 
on chronological order in the FACT files should merge the 
auxilliaries with FACT. SYS, sorting on date and time, before 
processing. 
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X,3 Processing Procedures 

Because each installation will have different needs for 
reporting and sumarizing computing activity, DEC does not 
attenipt to provide general purpose programs for processing 
the FACT files. It does, however, distribute two programs, 
MONEY and FACTPR which provide examples of how reporting 
programs could be written. MOMEY is a simple, supported, 
reporting program, written in MACRO, whereas FACTPR is an 
unsupported conversion program, suitable for use as a 
pre-processor to a complex reporting system which might be 
vrritten in COBOL, 



2.0 DEC-DEFINED EITTRIES 

A 9«*bit byte in the first word of each entry identifies the 
type of the entry. The values 0, 377, and 777 in this type 
code are reserved as markers in the FACT files. Values from 
1 to 376 are reserved for definition by DEC, while 400 to 
776 are for cus toner definition. 



2.1 Basic Entry Format 

The first three words of every entry are the same, as 
follows t 



Word* 



Description 



header — 4 bytes, as follows: 
0-8 



9-17 



type code, which identifies 
reason for writing the entry, 
the format of the entry. If 
type code is even (bit 8«0) , 



date/time word 
format, with 
24-bit time in 
type code is 



the 
and 
the 
the 
old 
and 
the 



(2) is in 
12-bit date, 
jiffies. If 
odd (bit 8«1) , the 
date/ time word is in new standard 
date time format, and clock rate 
dependencies are not permitted in 
time representations. 

job number to which this entry 
refers. Usually, but not always, 
the job which created the entry. 
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18^29 terminal number (as In TTYnnn) to 
which the job is attached. CTY is 
indicated by 7777, and a detached 
job by 7776. 

30-35 length of the entry in words, 

including this header word. If an 

entry has only the basic 

information, this byte is 3. 

1 project-progriuraiier number to which this entry 
refers • 

2 date and time at which the entry was created, 
as follows s 

a. if header bit 8*0, old format: 

0-11 date, in system 12-bit format. 
12-35 tine, in clock ticks since 
midnight. 

b. if header bit B^l, new format t 

0-17 days since Nov. 17, 1858 
18-35 time, as a fraction of a day 



2.2 LOGIN (100), ATTACH (240) 

Mhen a user logs in, or attaches his terminal to a detached 
job, only the basic information (as described in 2.1) is 
stored if he is successful! 

Terminal and job numbers 
Project, progranser number 
Date and time of day 

If, however, the attempt is unsuccessful (e.g., he does not 
know the password) , then 20 is added to the type code, and 
the password he tried is recorded as word 3. Further, if 
the failure is due to a program's attempt to LOGIN an 
illegal job on a PTY under its control, the project 
programmer number of that job is recorded as word 4. LOGIN 
failures, therefore, are recorded as type t20, and ATTACH 
failures as 260. 
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2.3 CHKPNT (200) 

At ten-«dnute intervals throughout the operation of the 
systeii, so-called CHECKPOINT information is recorded about 
each Job in the system. In systems which use DAEMO N » it 
takes the CHECKPOINT at intervals controlled by the CHKTIM 
assenbly parameter. Other systems may use the CHKPNT 
program to record the same information. In addition to the 
basic information listed under 2.1, CHKPNT entries consist 
oft 

Word! Description 

3 job's accumulated run time, in milliseconds. 

4 job's integrated time-size product, in 
kilo-core-ticks • 

5 total disk blocks read by and for the job. 

6 total disk blocks written by and for the job. 

7 name of the program in the low segment, in 
SIXBIT. 



2.4 LOGOUT (140) 

When a user logs off the system, the l/yGOUT program records 
final values of all the CHECKPOINT information (except 
program nmnm) to sumarize the job. 



2.5 SPOOL (250) 

Each time the spoolers ccnplete a request, unless assembled 
with FACTSH zero, they call DAEMON to write a FACT file 
entry. The job and terminal numbers in the header word are 
those of the spooling program, but the PPN is that of the 
user for ifhon the spool request was performed. They record 
the following data in the FACT file, in addition to the 
basic informations 

word! Description 



three bytes s 

0-11 queue name in SIXBIT 
12-17 station number 
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18-35 APR serial nuxnber 

4 runtime used by the spooler for this request, 
in jiffies (clock ticks). 

5 kilo-core- ticks used by the spooler for this 
request. 

6 disk reads by the spooler for this request. 

7 disk writes by the spooler for this request. 



8 physical device name of the spooler output 
device. 

9 sequence number of the spool request. 

10 quantity of output in same units as output 
limits for this queue (e.g., pages, feet, 
etc.). 



2.6 SPACE (160) 

When the operator runs the (unsupported) SPACE program to 
evaluate disk utilization, he can ask it (with the /PACT 
switch) to record the current figures in the PACT file for 
later use by a billing program. This information includes, 
in addition to basic data, status of various variables in 
the retrieval information block of the file directory (UPD 
RZB) for each user on each file structure. The job and 
terminal numbers in the header word refer to those of the 
SPACE program, but the PPN is that of the UPD to which the 
entry refers. The rest of the entry iss 

Word! Description 

3 file structure name, in SIXBXT, on which this 
UPD was found. 

4 UPD status word (.RBSTS) from the UPD RIB. 

5 first come, first served quota (.RBQTP). 

6 logged-out quota (•RBQTO). 

7 reserved quota ( . RBQTR) • 

8 blocks presently allocated to this user 
(.RBUSD). 
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9 blocks remaining available for first come, 
first served allocation on this structure 
(•DCFCT). 

10 one of the following three words, in SIXBIT: 

CXJT there are no jobs logged in under 
this ppn. 

IN there is at least one job presently 
logged in under this ppn. 

RECOMP there are no jobs logged in, but 
the UFD status word shows the 
logged-in bit set. Allocation, 
therefore, needs to be recomputed 
for this user. If the /BATCH 
switch was specified, SPACE has 
submitted a dinnny batch job to 
force re-computation of allocation, 
but this job has not completed %^en 
the entry is written, so word 8 of 
the entry (.RBUSD) may be 
incorrect. 



2.7 Restart (370) 

Whenever DAENON is run (usually by the OPSRR auto startup 
file) , it writes a basic entry, indicating that the system 
was reloaded, so the processing program can reset itself, 
figuring that jobs not logged off in the PACT file were 
running %#hen the system crashed. 



2.8 Shutdown (372) 

Unimplconented, but intended to mar)c a scheduled system 
shutdown. 
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2.9 Hiatus (377) 

Whenever the FACT file is updated, the routine t^ieh adds a 
new entry checks the last word of the file (as indicated by 
the file length returned by LOOKUP) for the end-of-file code 
(see below). If the end-of-file indicator is not found, the 
routine backs up until it finds a non-zero word or the 
beginning of the block. Hiatus codes are then stored in the 
words backed over, to mark the spot where data may have been 
lost. 



2.10 Bnd-of-file (777) 

The last %iord in the FACT file should always be the 
end-of-file code. 



2.11 New Entry Types 

As developnent of DECsystem-10 software continues, it is 
likely that DEC will add new entry types to the FACT files. 
Customer programs which process the file, therefore, should 
be written to ignore, except possibly for a warning message, 
new codes %ihich appear in the file. This will ensure upward 
conpatability. 



3.0 CUSTOMER-DEFINED ENTRIES 

Entry types 400 through 776 are reserved for customer 
definition and implementation. DEC recommends that the 
format of the basic information words be followed in 
cus toner-defined entries, ^^o mechanisms are available for 
customers writing FACT file entries. The .FACT function of 
the DAEMON UUO is the easiest to use, (documented in UUOPRV, 
in the Specifications section of the Software Notebooks) but 
users with systems which do not run DAEMON may use the 
APPEND subroutine, which may be found in LOGIN, LOGOUT, or 
DAEMON, for instance. Note that the FACT file contains 
privileged information, and so is accessable only to jobs 
with JACCT or running under [1,2]. , 



[End of FACT.RNO] 



